Summary

This PR adds targeted guards to persistCoordinate in SharedLog to prevent unhandled rejections caused by a Time-of-Check-to-Time-of-Use (TOCTOU) race condition during node shutdown.

The issue: when _close() is called, it nullifies internal indices (_entryCoordinatesIndex, _replicationRangeIndex), but async operations already in the microtask/timer queue (triggered by replication events) still execute persistCoordinate. The existing !this.closed check in findLeaders passes before _close() completes, but by the time persistCoordinate runs, the indices are gone — causing TypeError: Cannot read properties of undefined.

Root Cause Analysis

This was identified as Root Cause B in a systematic investigation of SharedLog teardown races. Three hypotheses were tested in parallel using isolated git worktrees:

Changes

Four-layer guard added to persistCoordinate (~line 3662 in index.ts):

1. this.closed early bail — catches the common case where close has already completed
2. Entry hash validation — ensures the replication entry is valid before proceeding
3. Index existence checks — verifies entryCoordinatesIndex and _replicationRangeIndex haven't been torn down by _close()
4. Try/catch with post-execution closed check — handles the narrow TOCTOU window where _close() completes mid-execution; swallows the error if we're now closed (expected during shutdown), re-throws otherwise

async persistCoordinate(...) {
  if (this.closed) return;                          // Guard 1
  if (!entry?.hash) return;                         // Guard 2  
  if (!this.entryCoordinatesIndex) return;          // Guard 3
  if (!this._replicationRangeIndex) return;         // Guard 3
  try {
    return await originalPersistCoordinate(...);     // Original logic
  } catch (err) {
    if (this.closed) return;                        // Guard 4
    throw err;
  }
}

Test Results

Methodology: Full vitest test suite (178 tests) run on each worktree. Integration tests (library, playlist, identity, replication.boundaries) also run 3x separately to check for flakiness.

Full Suite Results

Remaining 2 Errors

The remaining 2 unhandled errors originate from @peerbit/program's RPC layer (RPC.close → TypedEventEmitter.dispatchEvent), not from SharedLog. These require a separate fix in the RPC/program teardown path.

Pre-existing Failures (unchanged, present on all branches)

• chunkedAesGcmV1.test.ts (2 failures)
• ProfilePage.test.tsx (2 failures)
• WalletPanel.purchaseForm.test.tsx (flaky, 0-12 failures)
• RecoverySetupPanel.test.tsx (1 failure)
• generateSampleMp3.test.ts (1 failure)

Relationship to PR dao-xyz#589

This fix is complementary to the pubsub subscribe race fix in PR dao-xyz#589 (dao-xyz#589). PR dao-xyz#589 fixes the root cause of dropped subscription messages during topic initialization. This PR addresses a separate race condition exposed during teardown — persistCoordinate executing after _close() has torn down internal indices. Both fixes are needed for a clean test suite.

Why This Approach Over Comprehensive Guards (Root Cause C)

Root Cause C added guards to handleSubscriptionChange, removeReplicator, and rebalanceParticipation as well. Testing showed zero incremental error reduction — all 4 eliminated errors came from the persistCoordinate guard alone. The minimal approach (this PR) is preferred because:

1. Smaller diff, easier to review
2. No behavioral changes to subscription handling or rebalancing logic
3. Same error reduction with less risk of unintended side effects